The README lacked context about what HEIC is, how iCloud exports produce these zips, and was missing documentation for several CLI flags entirely.

Changes

Content additions

• Background section explaining HEIC format, why it's not universally compatible, and the iCloud.com export workflow that produces the *icloud*.zip input files
• Step-by-step iCloud photo export instructions so users know how to prepare input before running the tool

CLI documentation

• Full reference table covering all 5 flags; --zip-pattern and --verbose were previously undocumented
• Explicit note that --extract-dir is a temporary directory that is auto-deleted after conversion

Developer experience

• pip install -e . dev install instructions (was absent)
• heic-converter installed console script usage example
• __main__.py added to project structure listing (was missing)

Opportunities to Improve section
Nine actionable enhancement ideas: output format flag (--format jpeg), parallel conversion via ThreadPoolExecutor, per-file error handling instead of aborting the batch, tqdm progress bar, EXIF metadata preservation, duplicate detection/skip, configurable --icloud-prefix, dry-run mode, and JPEG input support.

Badges
CI status, Python version, and license shields added to the header.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.